Skip to content

Add native USB serial discovery for Cyton and Cyton Daisy - #869

Open
Andrey1994 wants to merge 2 commits into
masterfrom
codex/serial-autodiscovery-187
Open

Andrey1994 wants to merge 2 commits into
masterfrom
codex/serial-autodiscovery-187

Conversation

@Andrey1994

Copy link
Copy Markdown
Member

When Cyton or Cyton Daisy is prepared with an empty serial_port, enumerate USB serial metadata without opening devices and connect only if exactly one FT231X candidate matches. An existing serial_number can select a USB dongle; ambiguous or missing matches fail before any port is opened. Explicit ports continue to bypass discovery.

Related to #187. This is a first implementation for Cyton/Cyton Daisy, not a claim of autodiscovery for every serial board. Keep the issue open for additional verified device descriptors and board-specific selection rules.

Implementation

  • Add internal Serial::get_port_info with Windows SetupAPI/Config Manager, Linux sysfs and macOS IOKit backends. No third-party runtime dependency; iOS/Android retain explicit-port operation.
  • Keep the Cyton VID/PID policy in C++ board-controller code rather than expanding public board-description JSON. No C ABI, binding signatures or input fields change.
  • Require a unique candidate after optional USB-serial filtering; never select by enumeration order or try alternate ports after an open/handshake failure. macOS uses only callout paths; Windows traverses to the physical USB device and excludes generated location IDs from USB serial numbers.
  • Replace the six-empty-read/500-read welcome limit with a monotonic deadline, empty-read backoff and bounded diagnostic storage. timeout=0 means six seconds; 1–600 means a custom welcome timeout. Flush before v, not after it, and clean up on a failed default-configuration write.
  • Document the native/libserialport/per-binding/probing alternatives, public API behaviour, limitations and concrete hardware acceptance criteria in docs/SerialPortDiscovery.rst.

Validation

  • Linux BoardController build with WARNINGS_AS_ERRORS=ON passed.
  • Dependency-free C++ regressions passed: zero/one/multiple candidates, ordering, duplicate/missing serials and metadata, Windows instance parsing, Linux sysfs fixtures, delayed/fragmented welcome, continuous noise, read failure and deadline expiry.
  • POSIX pseudo-terminal integration passed against the rebuilt library: Cyton and Daisy, two prepared sessions, explicit-port precedence, release/reopen and retry after handshake timeout.
  • AddressSanitizer/UndefinedBehaviorSanitizer passed with leak detection disabled because LeakSanitizer cannot inspect processes in this environment.
  • clang-format 12.0.1 and whitespace checks passed. Sphinx built the new design page and changed Cyton/Daisy documentation sections with warnings as errors.
  • Added a Windows/Linux/macOS CI matrix for the native tests and a Linux integration job. Native Windows/macOS execution is delegated to CI, not claimed as a local result.

Limits needing hardware verification

FT231X VID/PID identifies an adapter, not a guaranteed Cyton; unrelated FT231X products may match. A known USB serial or explicit port is recommended when these coexist, and the normal board handshake remains required. Physical dongles and driver variants have not been tested here. Ganglion/FreeEEG are not automatically enabled: their transport paths, USB identities and existing parameter semantics need separate verification. The synchronous welcome deadline can overrun by one backend read timeout.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-27T07:50:07.526893Z 669e0d5 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant